package com.southminority.ethnic.service.research;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.controller.research.vo.ResearchProjectVO;
import com.southminority.ethnic.pojo.ResearchProject;

import java.util.List;

/**
 * 科研项目服务接口.
 * <p>
 * 定义了科研项目模块的核心业务逻辑，包括前端展示和后台管理的所有功能。
 *
 * @author SouthMinority
 */
public interface ResearchProjectService {

    // =================================================================================
    // ==                             前端展示相关方法 (Public API)                     ==
    // =================================================================================
    
    /**
     * 分页查询已发布的科研项目列表（用于前端列表页）.
     *
     * @param page          当前页码.
     * @param size          每页显示数量.
     * @param projectType   项目类型 (可选, 'ongoing', 'completed').
     * @param level         项目级别 (可选).
     * @param year          开始年份 (可选).
     * @return {@link PageResult<ResearchProjectVO>} 封装了分页信息的查询结果.
     */
    PageResult<ResearchProjectVO> getPublishedProjectPage(Integer page, Integer size, String projectType, String level, Integer year);

    /**
     * 获取单个已发布项目的详细信息（用于前端详情页）.
     *
     * @param id 项目的唯一标识ID.
     * @return {@link ResearchProjectVO} 包含完整信息的项目视图对象.
     */
    ResearchProjectVO getProjectDetail(Long id);

    /**
     * 获取所有不重复的项目级别列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 项目级别字符串列表.
     */
    List<String> getProjectLevels();
    
    /**
     * 获取所有不重复的项目开始年份列表（用于前端筛选菜单）.
     *
     * @return {@link List<Integer>} 年份列表.
     */
    List<Integer> getProjectStartYears();


    // =================================================================================
    // ==                             后台管理相关方法 (Admin API)                      ==
    // =================================================================================
    
    /**
     * 分页查询所有科研项目信息（用于后台管理列表）.
     *
     * @param page          当前页码.
     * @param size          每页显示数量.
     * @param keyword       搜索关键词 (可选, 模糊匹配标题、负责人).
     * @param projectType   项目类型 (可选).
     * @param level         项目级别 (可选).
     * @param status        状态 (可选, 1-启用, 0-禁用).
     * @return {@link PageResult<ResearchProjectVO>} 封装了分页信息的查询结果.
     */
    PageResult<ResearchProjectVO> getProjectPageForAdmin(Integer page, Integer size, String keyword, String projectType, String level, Integer status);

    /**
     * 根据ID获取项目详情（用于后台管理编辑页）.
     *
     * @param id 项目的唯一标识ID.
     * @return {@link ResearchProjectVO} 包含完整信息的项目视图对象.
     */
    ResearchProjectVO getProjectDetailForAdmin(Long id);

    /**
     * 创建一个新的科研项目.
     *
     * @param project 包含项目所有信息的POJO对象.
     * @return {@link ResearchProjectVO} 创建成功后返回的项目视图对象.
     */
    ResearchProjectVO createProject(ResearchProject project);
    
    /**
     * 更新一个已存在的科研项目.
     *
     * @param id      要更新的项目的ID.
     * @param project 包含更新后信息的POJO对象.
     * @return {@link ResearchProjectVO} 更新成功后返回的项目视图对象.
     */
    ResearchProjectVO updateProject(Long id, ResearchProject project);
    
    /**
     * 根据ID删除一个科研项目（逻辑删除）.
     *
     * @param id 要删除的项目的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean deleteProject(Long id);
    
    /**
     * 批量删除科研项目（逻辑删除）.
     *
     * @param ids 包含多个要删除的项目ID的列表.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean batchDeleteProjects(List<Long> ids);
    
    /**
     * 更新指定项目的状态.
     *
     * @param id     项目的ID.
     * @param status 新的状态值 (例如: 1-启用, 0-禁用).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean updateProjectStatus(Long id, Integer status);
    
    /**
     * 设置或取消项目的重点展示状态.
     *
     * @param id         项目的ID.
     * @param isFeatured 是否重点展示 (1-是, 0-否).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean setProjectFeatured(Long id, Integer isFeatured);

    /**
     * 获取所有科研项目（过滤已删除），用于选择下拉。
     */
    List<ResearchProjectVO> getAllProjectsForAdmin();
} 
